home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Skunkware 5
/
Skunkware 5.iso
/
man
/
cat.1
/
xc.1
< prev
next >
Wrap
Text File
|
1995-07-25
|
51KB
|
1,321 lines
XC(L) XENIX/UNIX (printed 3/11/94)
Name
xc - communications program
Syntax
xxxxcccc [----lllldevice] [----ssssscript | ----tttt]
Description
XXXXcccc calls out over a serial port to another computer. It can manage an
interactive session or be called from ccccrrrroooonnnn(C). It has various means
for transferring files between computers, and can be partially or
totally under the control of scripts.
XXXXcccc starts up by reading the file ._x_c, which is sought for in this
order: in "XC_PATH", in the current directory, in your _H_O_M_E directory,
or in a default directory defined at compile time. This startup file
may contain any of the valid _S_E_T commands described below. XXXXcccc then
displays the current settings, and presents an <_X_C> prompt, unless
either the ----tttt or ----ssss option was present.
_O_p_t_i_o_n_s
----llll_d_e_v_i_c_e Use the specified _d_e_v_i_c_e, which need not be the full pathname,
e.g. "/dev/tty1A" or "tty1A" are equally acceptable. The line
could either be directly connected to another computer, or
have a modem on it. In either case (if a value was defined for
DIDO at compile time), xxxxcccc attempts to suspend a ggggeeeettttttttyyyy(M) pro-
cess that might be on that line, and then use the uuuuuuuuccccpppp(C)
_L_C_K.._f_i_l_e mechanism to lock the line.
----ssss_s_c_r_i_p_t Execute the specified _s_c_r_i_p_t after program startup.
----tttt Go directly to terminal mode. The default is to go to command
mode on program startup. This option is incompatible with the
----ssss option.
_E_n_v_i_r_o_n_m_e_n_t
If the environment contains a variable called "MODEM", then the value
of that variable will be the default device. As with the ----llll flag, this
need not be the full pathname. To set such a variable, in the Bourne
shell, you might say:
MODEM=tty01; export MODEM
or, in the C shell,
setenv MODEM tty01
If the environment contains a variable called "BYEttyxx", where "ttyxx"
stands for the basename of the modem line selected either by the MODEM
variable or by the "-l" command option, then the value of that variable
will be sent to the modem when the program terminates. This is useful
for setting the modem back to some preselected state. Example:
BYEtty01=ATZ ; export BYEtty01
Whatever string is contained in the "Byexxxxx" variable will be sent to
the modem preceded and followed by a carriage-return.
Newer modems can be preset to revert to a predetermined state when the
DTR signal of the computer is dropped, and so would not need to avail
themselves of this feature. Furthermore, ggggeeeettttttttyyyy programs which have been
suspended, and which restart as xxxxcccc exits, will reset a modem using
dialers or chat scripts referred to in the /usr/lib/uucp/Devices file.
The environment may contain a variable called "XC_PATH", consisting of
colon separated absolute paths to directories. If this variable is set
to, say, "/usr/joe/xc:/usr/lib/xc", then those two directories are the
first places searched for any scripts.
_C_o_m_m_a_n_d _M_o_d_e
When entering characters in command mode (that is, at the <_X_C> prompt),
control characters echo as ^x, where "x" is the control character that
was entered. Backspacing (using whatever key is defined in the current
environment) backspaces over both positions of the displayed control
character, as expected.
An "interpreted" key can be added in a manner similar to that of vvvviiii(C);
simply type ^V followed by the character to insert (backspace, delete,
carriage return, or newline).
The following commands are available at the <_X_C> command prompt:
cccc
cccciiiissss Respond to an ENQ signal for a CIS B-Plus protocol
transfer. This command is used for both uploading and
downloading from CompuServe.
dddd
ddddiiiiaaaallll Enter the dial directory. Returns to the <_X_C> prompt if
exited without dialing, but returns to terminal mode
after dialing or running a script.
ssss _f_i_l_e
ssssccccrrrriiiipppptttt _f_i_l_e Execute _f_i_l_e, which contains appropriate xxxxcccc script com-
mands. Returns to terminal mode when the script is com-
plete.
rrrrbbbb _f_i_l_e (XMODEM binary receive)
rrrrtttt _f_i_l_e (XMODEM text receive) Receive _f_i_l_e from the remote sys-
tem.
ssssbbbb _f_i_l_e (XMODEM binary send)
sssstttt _f_i_l_e (XMODEM text send) Transmit _f_i_l_e to the remote system.
sssseeeetttt [_o_p_t_i_o_n_s] Display or set the transmission parameters used by xxxxcccc.
See below.
tttt
tttteeeerrrrmmmm Enter terminal mode.
xxxx
qqqq
eeeexxxxiiiitttt
qqqquuuuiiiitttt Exit program. Return to invoking program/shell.
hhhh
hhhhaaaannnngggguuuupppp Hang-up the modem.
%%%%pppp _l_o_c_a_l__n_a_m_e [_r_e_m_o_t_e__n_a_m_e] Transmit (put) a file to a remote Unix
system. This command uses standard Unix utilities on the
other end. _R_e_m_o_t_e__n_a_m_e defaults to the same pathname as
_l_o_c_a_l__n_a_m_e if not otherwise specified.
%%%%tttt _r_e_m_o_t_e__n_a_m_e [_l_o_c_a_l__n_a_m_e] Receive (take) a file from a remote Unix
system. This command uses standard Unix utilities on the
other end. _L_o_c_a_l__n_a_m_e defaults to the same pathname as
_r_e_m_o_t_e__n_a_m_e if not otherwise specified.
????
hhhheeeellllpppp Displays a brief summary of xxxxcccc commands, the SET
options, and terminal-escape commands.
[Note: a compile-time option can disable the following three options to
prevent any access to shells or other programs outside of xxxxcccc.]
!!!! _c_o_m_m_a_n_d Execute the specified _c_o_m_m_a_n_d as a child process. If
_c_o_m_m_a_n_d is omitted, execute a local interactive shell.
(A space is required between the !!!! and the _c_o_m_m_a_n_d.)
!!!!!!!! Re-execute the last shell command string.
$$$$ _c_o_m_m_a_n_d Execute a shell _c_o_m_m_a_n_d with stdin and stdout redirected
to the modem port. This effectively puts the computer
into a "host" mode. (A space is required between the $$$$
and the _c_o_m_m_a_n_d.)
_U_s_i_n_g _t_h_e _S_E_T _C_o_m_m_a_n_d
The _S_E_T command is used to display and set/reset xxxxcccc's tunable parame-
ters. Any of these commands may be placed in the ._x_c file which is read
upon starting up xxxxcccc.
Used alone, _S_E_T displays xxxxcccc's current parameters.
The following parameters can be set (note that except in the case of
_n_a_m_es, these commands are case-_i_nsensitive, and that there alternative
forms of the commands shown on the XC help screen):
set auto on|off Sets the auto-capture feature. When entering terminal
mode, capturing commences without the necessity to
manually request it.
set bps _v_a_l_u_e
set baud _v_a_l_u_e Set the desired bits/second rate. Supported bps rates
are 300, 1200, 2400, 9600 (and, if included at compile
time, 19200 and 38400).
set cfile _n_a_m_e Set the _n_a_m_e of the capture file.
set cis on|off Set response to a CompuServe file transfer request
(<ENQ>). An "on" value specifies that when in terminal
mode, an <ENQ> character will launch a CIS B-Plus pro-
tocol transfer. This parameter should be set "off"
when not connecting to CompuServe, as phone line noise
may cause a bogus file transfer request.
set cr on|off In uploads using B-Plus protocol, setting this option
"on" will insert a carriage-return after each newline
in an ASCII file. If you expect your ASCII upload to
be captured by DOS users, it is best to set cr "on".
If your ASCII upload is meant strictly for Unix users,
then you may set cr "off". The B-Plus protocol imple-
mentation used by xxxxcccc will always strip end-of-line
carriage-returns from incoming ASCII files.
set dir _n_a_m_e Set the current working directory.
set menu on|off By default, a one-line menu is displayed above the
<_X_C> prompt to remind the user of options most fre-
quently chosen at this point: "[d]ial directory
[t]erminal mode [q]uit [s]cript [?]help". Setting the
option "off" turns off this display.
set nl on|off If this option is set "on", then newlines are sent as
carriage-returns. If this option is set "off", then
newlines are sent as newlines (carriage-returns are in
any case always sent as carriage-returns). This
option applies to input from the keyboard, or from a
disk file using the "XXXXCCCCAAAAPPPPEEEE FFFF" facility or a script
"type" command (See below). This option has no effect
on built-in XMODEM or B-Plus protocol transmissions,
and has no effect on incoming data.
set pfile _n_a_m_e Set the _n_a_m_e of the phone directory.
set proto _v_a_l_u_e This refers to the serial port character protocol, not
to a file transfer protocol. The possible values are
8N, 7E, or 7O, (case insensitive) which respectively
set the modem port to a character size of 8 with no
parity, or a character size of 7 with either even or
odd parity. During B-Plus or XMODEM transfers, the
port protocol is set to 8N, and reverts to its prior
setting thereafter.
set xcape _c_h_a_r
set escape _c_h_a_r Set the XXXXCCCCAAAAPPPPEEEE character (see below) to _c_h_a_r. This
should be set to some non-printing character (other
than backspace, tab, newline, of course). The charac-
ter may be entered by depressing the Control key first
and then typing a letter, or by typing a carat (^)
followed by a letter.
set xon on|off
set xoff on|off Set XON/XOFF flow control flag. If "on", the program
will honor the XOFF control character and wait until
an XON character is received before transmitting any
more information. If "off", the program will ignore
XOFF/XON requests.
_T_e_r_m_i_n_a_l _M_o_d_e
In terminal mode, all characters typed at the keyboard are sent to the
modem, except that newline characters (0x0A) are translated to
carriage-returns (0x0D) when you have "set nl 'on'"; all characters
received from the modem are displayed on the local terminal screen.
XXXXCCCCAAAAPPPPEEEE is a key that will, when typed in terminal mode, introduce an xxxxcccc
"escape" command. Don't confuse XXXXCCCCAAAAPPPPEEEE with the <ESCAPE> key. The
default definition for XXXXCCCCAAAAPPPPEEEE is ASCII 1, or Control-A. It can be rede-
fined at run time with the "set escape _C" command (or it can be rede-
fined in the ._x_c startup script).
When the XXXXCCCCAAAAPPPPEEEE key is typed in terminal mode, the program will examine
the next key pressed. If this key has been "bound" to perform a certain
function, that function will be performed; otherwise, the second char-
acter is sent to the modem. Thus, to send the XXXXCCCCAAAAPPPPEEEE character through
the modem, it is necessary to press the key TWICE.
Thus the ESCAPE key itself would be a terrible choice for XXXXCCCCAAAAPPPPEEEE,
because it is used so often by other programs: if you were logged into
a remote system and running, say, vvvviiii, it would be a great annoyance to
have to hit ESCAPE twice to get it transmitted once.
The following keys (case _i_nsensitive) are bound at startup time. Others
may be added through the binding commands available in xxxxcccc scripts.
Command Function Description
XXXXCCCCAAAAPPPPEEEE //// Help Display the table of bound keys
XXXXCCCCAAAAPPPPEEEE ???? Help Display the table of bound keys
XXXXCCCCAAAAPPPPEEEE bbbb _BREAK Send a MODEM BREAK signal (a sustained null).
XXXXCCCCAAAAPPPPEEEE dddd _Directory Display the phone directory.
XXXXCCCCAAAAPPPPEEEE ffff _File Send a file through the modem (ASCII transfer).
XXXXCCCCAAAAPPPPEEEE ssss _Script XXXXcccc will request the name of a script to execute.
XXXXCCCCAAAAPPPPEEEE hhhh _Hangup Tell the modem to go on-hook.
XXXXCCCCAAAAPPPPEEEE yyyy Capture _Yes Open the capture file in APPEND mode (text
received over the port accumulates at the end of
the file). If the file is already open, a mes-
sage is printed to that effect.
XXXXCCCCAAAAPPPPEEEE nnnn Capture _No Close the capture file. If it wasn't open, a
message of regret is printed.
XXXXCCCCAAAAPPPPEEEE xxxx e_Xit Exit terminal mode back to _<_X_C_> command mode.
XXXXCCCCAAAAPPPPEEEE qqqq _Quit Quit xxxxcccc altogether.
_P_h_o_n_e_l_i_s_t
XXXXcccc looks for a ._p_h_o_n_e_l_i_s_t file in the following order: in the current
directory, in your home directory as defined by the $HOME environment
variable, or in the LIBDIR as defined at compile time in _x_c._h. However
in command mode, any filename can be substituted, using the SET PFILE
command, so long as it has the following characteristics:
It is ASCII text (lines of text separated by newlines).
The first field of data in each line (after any whitespace and up to
the next occurence of whitespace) is a phone number in a valid format
for the modem being used.
Descriptive text may follow the phone number. Spaces may be included in
this text, but a <TAB> must terminate this text.
The following three definitions may then follow in any order:
PROTO=sss (sss=7e|7o|8n) Set the serial port protocol for 7-bit char-
acters with either even or odd parity, or for 8-bit charac-
ters with no parity.
BPS=nnnn (n=300|1200|2400|9600|19200|38400) Set the bits/second rate
to the specified value.
SCRIPT=file Immediately after sending the autodial string, execute the
script file specified. (Note that the specified filename is
CASE SENSITIVE!)
The following definition, if used, must be the LAST field on the line.
PREFIX=xxxxxxxx (e.g., PREFIX=ATs110=0s111=0)
The PREFIX="string" allows you send your modem a different setup string
for each situation (default: no special setup). This is helpful for MNP
and Telebit modems which require special attention for contacting non-
MNP modems and other Telebits.
_S_c_r_i_p_t_s
The xxxxcccc script language is intended to be closely similar to the Unix
Bourne shell language. Unfortunately, it isn't identical to the Bourne
shell, so it has the same problem that the aaaawwwwkkkk(C) program does for
those experienced in the C language: an aaaawwwwkkkk script LOOKS like C, but it
isn't, really; and in the same way, an xxxxcccc script LOOKS like a Bourne
shell script, but isn't. So the operation of the Bourne shell, if
you're familiar with it, is useful as an analogy in understanding the
xxxxcccc script language, but only as an analogy.
An xxxxcccc script consists of lists of commands. Commands are set off from
each other within a list by either a newline ('\n') or a semicolon (;),
as is the case with the Bourne shell. The semicolon and the newline
have identical effect as command separators, so (anticipating a bit
here) you could say either
if counter morethan 5
then
transmit "bye^M"
quit
endif
or
if counter morethan 5; then transmit "bye^M"; quit; endif
and the result will be the same either way. The newline and the semi-
colon are treated the same way as in the Bourne shell, except that a
newline cannot be quoted so as to remove its interpretation as a com-
mand terminator (in other words, a quoted string cannot contain a new-
line).
Commands are composed of _w_o_r_ds separated by spaces or tab characters,
and a _w_o_r_d can be one of the following:
* One of the xxxxcccc script language keywords, which are listed below, with
appropriate explanations.
* A number, meaning a sequence consisting only of digits, with an
optional leading minus sign to indicate a negative number.
* A literal string of characters surrounded by double-quotation marks
('"'); such a string can be no longer than 80 characters. A double-
quotation mark can be imbedded within the string by preceding it
with a backslash ('\"'); when the string is interpreted, the
backslash is disregarded and the double-quotation mark is treated as
part of the string. Mismatched quotation marks result in a syntax
error.
* The name of a user variable, which can have either a string or a
numeric value. The name of a user variable must begin with an
alphabetic character.
* The name of a shell environment variable, preceded by a dollar sign
('$'). The xxxxcccc script language examines the Unix environment for the
specified variable and, if such a variable exists, substitutes the
value of that variable. The result is treated as if it were a quoted
literal string, and, therefore, should not be more than 80 charac-
ters long, or else it will be truncated to its first 80 characters.
Similarly, such an environment variable should not contain a new-
line.
* An expression surrounded by back-quotation marks ('`'). This sort of
expression operates similarly to the Bourne shell's command-substi-
tution mechanism: the contents of the back-quotes are passed to the
Bourne shell, and the standard output of the back-quoted command is
treated as if it were a quoted literal string. Therefore, the
command's output should not be more than 80 characters long, nor
contain a newline. Also, the contents of the back-quotes cannot be
longer than 80 characters, nor contain a newline.
* An expression introduced by a pound-sign (or number-sign: '#'),
which is treated as a comment. All characters from the '#' until the
end of the physical line are ignored. This comment mechanism is the
same as in the Bourne shell.
* A limitation of the script language is that only one character
string can be passed as an argument to any of the script commands.
The _b_i_n_d__f_u_n_c_t_i_o_n, _b_i_n_d__s_c_r_i_p_t, and _b_i_n_d__s_t_r_i_n_g commands thus need
to use a decimal digit to represent the key that is to be bound. The
ASCII value of the the key is employed. As an example, Control-C is
identified as 3, Control-Z is 26, the ESCAPE key is 27, a space is
32, the number "1" is 49; letters are case-_i_nsensitive so that iden-
tifying the bound key as "65" or as "97" will always bind _b_o_t_h "a"
and "A" to the same command.
Quoted literal strings (and the two other mechanisms that act like
quoted literal strings, shell environment variables and back-quoted
shell commands) may be up to 80 characters long. All other words must
be no longer than 16 characters, and are treated case-independently
(which is to say, uppercase is the same as lowercase); note, though,
that the names of shell environment variables are case-dependent
(uppercase must match uppercase and lowercase must match lowercase),
because they are case-dependent in the shell.
Any word not recognizable within the foregoing categories is treated as
the name of a new user variable. Such a word, if longer than 16 charac-
ters, is considered to be a syntax error.
User variables are created with the 'assign' script keyword, and may
have either numeric or string values. The type of a user variable is
determined by how it's created; if it's assigned to a string, it's a
string variable, and if it's assigned to a number, it's a numeric vari-
able. The value of any user variable can be changed with another
'assign' command, and numeric variables can be changed to string vari-
ables and vice-versa. Shell environment variables cannot be changed
within an xxxxcccc script, but the value of a shell environment variable can
be assigned to a user variable, and the value of the user variable can
thereafter be changed.
Scripts are contained in ASCII text disk files, one script to a file. A
script can invoke another script as a subroutine with the 'call' key-
word; up to 5 scripts can be nested in this way at any single time.
With all this said, the following list of xxxxcccc script language commands
should be comprehensible. The format "<something>" means that a token,
or word-type, of the "something" type is meant rather than the literal
sequence 'something'.
_S_c_r_i_p_t _L_a_n_g_u_a_g_e _C_o_m_m_a_n_d_s
Note that all the commands are case-_i_nsensitive!
_a_f_f_i_r_m
Syntax: affirm
Reads a string from the terminal, and returns TRUE if the string
begins with 'y' or 'Y'; otherwise, returns FALSE. Used in evaluat-
ing conditional expressions. The string must be terminated by a
newline or carriage-return.
Example:
echo -n "Continue (y/n)? "
if affirm
then
continue
else
break
endif
_a_s_s_i_g_n
Syntax: assign <varname> eq <number>
assign <varname> eq "string"
assign <varname1> eq <varname2>
assign <varname> eq <script-command>
Assigns to user variable <varname> the value following "eq"; if
that value is a number, then <varname> becomes a numeric user vari-
able; if that value is a string, then <varname> becomes a string
user variable. If <varname> does not already exist as a user vari-
able, it is created. Variable space is allocated dynamically, but
running out of memory space for variables is unlikely. All vari-
ables are global across scripts that run at the same time via the
'call' keyword, and all variables vanish when a script, called
directly from xxxxcccc as opposed to called from another script, exits.
In other words, variable values are not static except during 'call'
execution. Variable names cannot be longer than 8 characters. Suc-
cessive 'assigns' are permissible, and the type of the variable
changes according to the type of the value following "eq". A user
variable is destroyed with the 'unassign' keyword.
If a variable is assigned the value of a script command, then it
becomes a numeric variable with value TRUE or FALSE, depending on
the status returned by the script command. If a variable is
assigned the value of a back-quoted command, it becomes a string
variable with the value of the first 80 characters of the back-
quoted command. If a variable is assigned equal to an environment
variable, it becomes a string variable with the value of the first
80 characters of the value of the environment variable.
Examples:
assign numvar eq 5
assign strvar eq "This variable is a string"
assign mydir eq $HOME
assign numvar2 eq numvar
assign strvar2 eq strvar
assign numvar eq true
assign today eq `date`; echo "today is " today
_b_e_e_p
Syntax: beep
Sends a Control-G to the terminal. Useful for alerting the user
that some event has occurred, for example a CONNECT after a lengthy
redialing session.
_b_i_n_d__f_u_n_c_t_i_o_n
Syntax: bind_function _c_o_d_e "function"
Bind the character identified by the number specified by _c_o_d_e to
the xxxxcccc builtin function "function".
The "function" may be one of the following (case is ignored):
BRKCHAR Send modem BREAK signal
CAPTEND Turn off terminal mode capture
CAPTYES Turn on terminal mode capture
DIALCHR Dial from phonelist
DIVCHAR Send file through modem
DOSCRPT Execute script file (prompts interactively)
EMITSTR Emit string
ENDCHAR Exit terminal mode
HLPCHAR Display terminal mode key bindings
HUPCHAR Hang up modem
QUITCHR Quit program
SCRPCHR Prompt for script file
Example:
bind_function 26 "quitchr"
This binds Control-Z to quit the XC program.
_b_i_n_d__s_c_r_i_p_t
Syntax: bind_script _c_o_d_e "scriptname"
Bind the character identified by the number specified by _c_o_d_e to
execute the script named by "scriptname".
Upon termination of the script, the program will resume terminal
mode, unless the "quit" script function was executed.
Examples:
bind_script 18 "/usr/lib/xc/.rz"
This binds Control-R to execute the script /usr/lib/xc/.rz. The .rz
script supplied with the source code contains:
tty "on"
echo -n "What files are to be received? "
read FILES
transmit "sz -y "
transmit FILES
transmit "^M"
echo "Starting ZMODEM Receive (rz -y)"
pipe "rz -y"
Pressing XXXXCCCCAAAAPPPPEEEE ^^^^RRRR will ask for some file name(s), and start an sssszzzz
command on the remote system, and an rrrrzzzz on the local system to
receive the file(s).
bind_script 19 "/usr/lib/xc/.sz"
This binds Control-S to execute the script /usr/lib/xc/.sz. The .sz
script supplied with the source code contains:
tty "on"
echo -n "What files are to be sent? "
read FILES
echo "Starting ZMODEM send (sz -y " FILES ")"
pipe "sz -y " FILES
Pressing XXXXCCCCAAAAPPPPEEEE ^^^^SSSS will ask for some file name(s), and then launch
sssszzzz on the current system. SSSSzzzz will itself start an rrrrzzzz process on
the remote system.
_b_i_n_d__s_t_r_i_n_g
Syntax: bind_string _c_o_d_e "string"
Bind the character identified by the number specified by _c_o_d_e to
emit the string specified by "string".
The string is sent to the modem untranslated; eg, it is not exam-
ined for embedded terminal mode escapes.
Example:
bind_string 49 "AAATZ^M"
This binds "1" to send the sequence to reset the modem.
_b_r_e_a_k
Syntax: break
Exits from the immediately enclosing 'while' loop. Identical to the
C language 'break', and to the Bourne shell 'break' except that the
xxxxcccc script language 'break' does not take a numeric argument. Don't
confuse this with the script keyword 'xmitbrk', which sends a BREAK
signal to the modem port.
_c_a_l_l
Syntax: call "scriptname"
Suspends execution of the current script, and attempts to load and
run the specified scriptname. The scriptname must be a quoted
literal string. There is no xxxxcccc analogue of the Bourne shell "exec"
command; all subscripts in xxxxcccc are treated as sub-routines. All
variables are global across subscripts, so if a subscript changes
the value of a variable, then that change will remain in effect
after return to the parent script. Shell environment variables can-
not be changed by any xxxxcccc script.
_c_a_p_t_u_r_e
Syntax: capture "on"
capture "off"
Turns the file-capture function on or off. Note that the arguments
must be quoted literal strings. Note also that when the script
exits into terminal mode, the file-capture function is turned off.
If you have 'set auto "on"', then you will begin capturing immedi-
ately upon entering, or returning to, terminal mode. If not, then
you must manually type "XXXXCCCCAAAAPPPPEEEE YYYY" to start capturing when entering
terminal mode.
_c_o_n_t_i_n_u_e
Syntax: continue
Resumes execution at the top of the immediately enclosing 'while'
loop. Identical to the C language 'continue' instruction, and to
the Bourne shell 'continue' command except that no numeric argument
is accepted.
_d_e_b_u_g
Syntax: debug "on"
debug "off"
If the 'debug' option is on, then xxxxcccc will make many parenthetical
comments about what it's doing while it runs the script. These com-
ments can sometimes be helpful in debugging script logic. Note that
the argument must be a quoted literal string.
While debugging a script containing a password, turn this option
off, then on again, to reduce the excitement-level of any col-
leagues collected circa your screen.
_d_e_c_r
Syntax: decr <numeric-variable>
Decrements the value of the specified numeric user variable by 1.
Useful in controlling loop execution. If the specified variable
isn't numeric, or doesn't exist, a syntax error results.
_d_i_a_l
Syntax: dial "number-string"
Dials the specified number, using modem-command strings defined in
xc.h. The number should not contain spaces; dashes are acceptable.
_e_c_h_o
Syntax: echo "string" <variable> ...
echo -n "string" <variable> ...
This command sends its arguments to the user's terminal. The number
of arguments is optional, except that the total result may not
exceed 80 characters. Variables and back-quoted shell commands are
expanded as necessary.
If the "-n" switch is present, then no carriage-return/newline
sequence is appended to the output.
Examples:
echo "The time and date are now " `date`
echo "My terminal type is " $TERM
echo "My terminal type is " $TERM " today."
Note that whitespace isn't echoed unless it's part of a quoted
literal string.
_e_x_i_t
Syntax: exit
Terminates execution of the current script. If a script reaches its
end, it exits automatically, so 'exit' is useful mainly to ter-
minate a script prematurely.
_f_a_l_s_e
Syntax: false
Same as the Unix 'false' command. Does nothing, but returns a FALSE
status value. Useful within conditional expressions.
Example:
if waitfor "CONNECT" 30 eq false
then
quit
endif
Note that above example could be rewritten using the negating
modifier "!":
if ! waitfor "CONNECT" 30
then
quit
endif
and note too that the "!" must be separated from its argument by
whitespace.
_f_i_l_e
Syntax: file <script-command>
The standard output of the specified script command is sent to the
current capture file. If the "capture" option is not set, then an
error message is displayed, but script execution continues.
Examples:
file echo "--------- CUT HERE ----------"
Sends the output of the 'echo' command to the current capture file,
provided that the "capture" option is now "on".
file echo `date`
Sends a timestamp to the current capture file, provided that the
"capture" option is now "on". The same thing could have been done
with
file shell "date"
_h_a_n_g_u_p
Syntax: hangup
Tells the modem to go on-hook.
_i_f
Syntax: if <list1>; then <list2>; [ else <list3>; ] endif
If <list1> evaluates as TRUE, performs <list2>; otherwise, if
<list3> is specified, performs <list3>; then resumes execution
immediately following 'endif'. To accommodate those whose minds
wander while writing scripts, 'fi' is an acceptable synonym for
'endif'.
Each list may consist of any number of script commands separated by
semicolons or newlines. The value of <list1> is determined by
inclusively OR'ing the value of each directive in the list, so that
if any of the directives in <list1> evaluates as TRUE, then so will
<list1>. <list1> is performed in its entirety regardless of the
value of any of its component commands.
The keywords 'then', 'else', and 'endif' (or 'fi') must be immedi-
ately preceded by command separators, either a semicolon or a new-
line, just as is the case in the Bourne shell.
For conditional evaluation in 'if' and 'while' constructions, the
following comparators are available in addition to the script
directives mentioned elsewhere:
<varname1> eq "string"
<varname1> eq <number>
<varname1> eq <varname2>
<varname1>
"string"
evaluates as TRUE if the value of user variable <varname1> is the
same as that of a specified string or numeric constant or of a
specified second variable name. If the variable name <varname1> is
not followed by anything else, then the expression evaluates as
TRUE if the variable is numeric and has a non-zero value, or if the
variable is a string variable and has a non-zero length; otherwise,
the expression evaluates as FALSE. Comparing a string variable to a
numeric variable, or vice-versa, causes a syntax error.
If a conditional expression consists only of a quoted literal
string, the expression evaluates as TRUE if the string's length is
non-zero, and otherwise evaluates to FALSE. Because environment
variables and back-quoted shell commands are treated as if their
output/value were quoted literal strings, this allows direct test-
ing of a shell command or of an environment for non-zero length.
Nonexistent environment variables are treated as if they exist with
the value "" (a string of zero length).
<varname1> neq "string"
<varname1> neq <number>
<varname1> neq <varname2>
evaluates as TRUE if the value of user variable <varname1> is not
equal to that of a specified string or numeric constant or of a
specified second variable name. Comparing a string variable to a
numeric variable, or vice-versa, causes a syntax error.
<varname1> lessthan "string"
<varname1> lessthan <number>
<varname1> lessthan <varname2>
evaluates as TRUE if the value of user variable <varname1> is less
than that of a specified string or numeric constant or of a speci-
fied second variable name. String variables are compared lexically
according to ASCII value.
<varname1> morethan "string"
<varname1> morethan <number>
<varname1> morethan <varname2>
operates identically to 'lessthan', except in reverse.
The value of any conditional expression may be negated by preceding
it with an exclamation point followed by a space or tab.
Examples:
if counter eq 0; then break; endif;
if var1 eq var2; then echo "identical"; endif
if counter morethan 20; then break; endif;
if counter lessthan 0; then break; endif;
if ! counter; then echo "counter is " counter; endif
To perform a list if any of a set of conditions exist:
if counter morethan 5;
counter eq brkvalue; # a second comparator
then break;
endif;
i.e., perform the 'break' directive if the value of numeric user
variable 'counter' is greater than the numeric constant 5, or if
the value of 'counter' is equal to that of the user numeric vari-
able 'brkvalue'.
_i_n_c_r
Syntax: incr <numeric-variable>
Increments the value of the specified numeric user variable by 1.
The opposite of 'decr'.
_l_i_n_k_e_d
Syntax: linked
'linked' is a pseudo-function that evaluates as TRUE if the current
script has been invoked from the dialing directory, and as FALSE
otherwise.
Example:
if ! linked; then
dial "5551212"
endif
_p_a_u_s_e
Syntax: pause <number>
Suspends execution for the specified <number> of SECONDS. Identical
to Unix "sleep."
_p_i_p_e
Syntax: pipe "<shell-command>"
The standard input and standard output of the specified shell com-
mand are connected to the modem port, and the command is executed.
This is the equivalent of the command mode "$" command.
Examples:
pipe "echo \"\177\""
sends a DELETE character to the modem.
pipe "rz"
performs a file receive via ZMODEM, assuming that Chuck Forsberg's
'rz/sz' programs reside on your system.
_p_o_r_t_n_a_m_e
Syntax: portname
This isn't a command, but a synonym for the current modem terminal
device, treated as if it were a quoted string. Useful if modems of
differing types are attached to different terminal lines and need
different dialing or initialization sequences. To compare the value
of 'portname' to some other string, you must first assign a user
variable equal to 'portname'.
Examples:
assign myport eq portname
if myport eq "/dev/tty01"
then
transmit "AT&E0^M"
endif
_q_u_i_t
Syntax: quit
Exits the script and terminates xxxxcccc entirely. Any LCKfile will be
removed if possible and the user's terminal will be restored to the
state it was in when xxxxcccc was invoked.
_r_e_a_d
Syntax: read <variable-name>
Takes a string from the user's keyboard and places it into the
specified user variable. Any previous value of the specified vari-
able is discarded.
_r_e_d_i_a_l
Syntax: redial
Redials the number most recently dialed with the 'dial' command.
_s_e_e_n
Syntax: seen "string" <number>
Evaluates as TRUE if "string" has occurred within the last <number>
characters received during the most recent 'waitfor' command. Only
up to 2048 characters are remembered at any one time during 'wait-
for' processing. If no <number> is specified, then all the charac-
ters received during the most recent 'waitfor' command are exam-
ined, up to a maximum of 2048. The 'seen' buffer is reset at the
beginning of each 'waitfor' command. This is useful to tell which
of several strings has been received.
Example:
if waitfor "string1" 20
then
echo "Received 'string1'."
else
if seen "string2"
then
echo "Received 'string2' instead."
endif
endif
_s_e_t
Syntax: set <xxxxcccc-set-option> <value>
This command is the same as the command-mode xxxxcccc 'set' command, such
as "set bps 1200", "set cis on", and so forth, except that a string
<value> must be enclosed within double-quotation marks.
Examples:
set cis "on"
set cfile "newfilename"
set auto "on"
set bps 2400
_s_h_e_l_l
Syntax: shell "<shell-command>"
The shell command enclosed within the double-quotation marks is
executed. This is similar to the xxxxcccc command-mode "!" command.
Remember that if the shell command contains double-quotation marks,
they must be escaped with backslashes.
_t_i_m_e_o_u_t
Syntax: timeout <number>
If <number> is greater than zero, starts a timer which will cause
the MOST DEEPLY NESTED script to exit when <number> of MINUTES
expire. If <number> is zero, then any pending timeout is cancelled.
If <number> is negative, nothing happens.
Expiration of the specified timeout causes the most deeply nested
script to exit, not to terminate xxxxcccc. To cause the program to quit
if a timeout expires, use a subscript.
Example:
'script1' contains:
call "script2"
if expired
then
quit
endif
# more commands
'script2' contains:
assign expired eq 1
timeout 5 # limit of 5 minutes
while ! waitfor "login:" 30
do
xmitbrk
done
assign expired eq 0
exit
When 'script2' exits, the numeric variable 'expired' will be set to
1 if 'script2' timed out, and will be 0 otherwise. 'script1' can
act on this information accordingly.
_t_r_a_n_s_m_i_t
Syntax: transmit "string"
Sends a string to the modem. The string is sent with brief pauses
between characters, to accommodate modems that cannot accept rapid
command input, and within the string, any alphabetic character pre-
ceded by a caret (^) is translated to the corresponding Control-
character.
Example:
transmit "ATDT 5551212^M"
sends the string "ATDT 5551212" to the modem, followed by a
carriage-return character.
_t_r_u_e
Syntax: true
Does nothing, but always evaluates as TRUE. Useful in conditional
expressions. The opposite of 'false'.
_t_t_y
Syntax: tty "on"
tty "off"
Ordinarily, during script execution, characters received from the
modem port are echoed to the user's terminal screen. This happens
only during 'waitfor' and 'type' execution, so it may be a bit
choppy. This echoing can be turned off with
tty "off"
and turned back on with
tty "on"
Note that "on" and "off" must be enclosed in quotation marks.
_t_y_p_e
Syntax: type "<filename>"
Sends the specified ASCII file to the modem port. This is the same
as the xxxxcccc terminal-mode "send ASCII file" escape.
_u_n_a_s_s_i_g_n
Syntax: unassign <variablename>
Erases the specified user variable. The variable may be either
numeric or string type. The variable name must not be enclosed in
quotation marks, because variable names are considered to be xxxxcccc
script keywords, and not literal strings.
_w_a_i_t_f_o_r
Syntax: waitfor "string" <number>
Scans input from the modem port for an occurrence of the specified
string, which must be enclosed in quotation marks. The scanning
continues for the specified <number> of SECONDS or until the speci-
fied string is identified in the modem input stream, whichever
comes first. This command evaluates as TRUE if the specified string
is found, and as FALSE if the specified <number> of SECONDS elapses
and the string isn't found within that time. The default time, if
no <number> is specified, is roughly 30 seconds.
String matching is performed on a case-_i_nsensitive basis. Within
the string, any alphabetic character preceded by a caret (^) is
translated to the corresponding Control-character.
Examples:
assign counter eq 1
while ! waitfor "login:" 15
do
xmitbrk; incr counter; if counter morethan 5
then
quit
endif
done
If in a CompuServe Forum the "prompt character" has been set by the
user to be a backspace, this test will log off if the main prompt
is not seen in the next sixty seconds:
if ! waitfor "forum !^H" 60
then
transmit "bye^M"; quit
endif
If the 'cis' option has been set to "on", either in the ._x_c startup
script, or by a direct 'set' command from command mode, or with
set cis "on"
within a current script, and if during 'waitfor' processing a CIS
B-Plus protocol file transfer request is received, then the B-Plus
protocol transfer is performed, the <number> argument is reset to
its original value, and 'waitfor' processing continues. This allows
automatic B-Plus protocol file transfers from within a script.
_w_h_i_l_e
Syntax: while <list1>; do <list2>; done
Operates similarly to the 'if' command, except that <list2> is exe-
cuted repeatedly so long as <list1> evaluates as TRUE. All the con-
ditional comparators and rules for comparisons that apply for the
'if' command also apply to 'while'. (Note that 'while' loops can be
nested within 'if' commands and vice-versa.)
_x_m_i_t_b_r_k
Syntax: xmitbrk
Sends a BREAK signal to the modem port.
_F_i_l_e _T_r_a_n_s_f_e_r_s
When transferring files using the XMODEM protocol, the file mode is
specified in the upload/download command. A TEXT mode transfer enables
translation of the transmitted or received file to support CP/M and
MS-DOS end-of-line characters. When transmitting a file using TEXT
mode, all newlines are converted to carriage-return/newline sequences.
When receiving a file using TEXT mode, all carriage-return/newline
sequences are converted to just a newline. A BINARY mode transfer
transmits the file "as is" without any such conversion.
When transferring files using CompuServe B-Plus protocol, the format of
the file is specified by the host. An ASCII mode will force xxxxcccc to per-
form TEXT mode translation; a BINARY mode will not do any translation.
This means that, in either direction, a BINARY mode will send bytes "as
is", whereas in ASCII mode, an incoming file will always be stripped of
end-of-line carriage-returns, while an ASCII file being uploaded may or
may not have carriage-returns added after each newline, depending on
the "on" or "off" setting of the "cr" option.
When using either the "%t" (take) command, an XMODEM receive command,
or a CompuServe B-Plus download command, xxxxcccc will check if the file name
you specify already exists on your system, and ask for an OK to
overwrite the file, or for an alternative name. In the CompuServe case,
there will also be an option to "Resume" a download. If the CRC check-
sum of the bytes that you already have in the file matches CompuServe's
checksum on the the same initial bytes in its version of the file, file
transfer will proceed from that point onwards. This saves connect time
when a very large download has been interrupted during a prior session.
Script-driven file transfers using the CompuServe B-Plus protocol are
more or less built into the xxxxcccc script language, since during 'waitfor'
processing, a file transfer request from the modem port will trigger a
B-Plus transfer if the "cis" mode is set. The difficulty in performing
such transfers isn't in the transfer itself, but rather in the
maneuvering required to get into position to transfer the correct file,
and is something that probably only experienced script writers should
wrestle with. However, if we assume that in the midst of a script,
you've reached a point where you can issue a "download" command to Com-
puServe, for instance a "Disposition" prompt during a File Library
"BROWSE" command, and you want to download the present file, which is
"XCALL.C" on CompuServe, and "xcall.c" does not exist in your current
working directory, you'd use the following sequence of script commands
to do it:
set cis on # can't do auto file B-Plus transfer otherwise
transmit "dow^M"
pause 2 # wait for CIS to display protocol menu
transmit "2^M" # B-Plus is number 2 on that menu
transmit "xcall.c^M" # "file name for your computer:"
waitfor "Disposition"
During the final "waitfor" processing, the CompuServe ENQ character
will be recognized and the transfer will proceed automatically. Then
'waitfor' will continue waiting for the "Disposition" prompt, after
which your script can proceed. The same sort of thing can be done with
file uploads, but once again, the difficulty isn't with the transfer,
but rather with setting things up so that the transfer will be
requested at the correct place.
A shell script, cccciiiissssddddoooowwwwnnnnllllooooaaaadddd provided with the distribution, can
automatically retrieve a single file from a CompuServe library.
For XMODEM, YMODEM, and ZMODEM transfers via scripts, there's no
mechanism built into the xxxxcccc script language to use the built-in, 128-
byte-packet XMODEM in xxxxcccc. Instead, we strongly recommend that you
obtain Chuck Forsberg's excellent, shareware utility called "RZSZ",
which can handle XMODEM, XMODEM-1K, YMODEM, and ZMODEM transfers and
which can be used from within xxxxcccc with the 'pipe' command, or from com-
mand mode with the '$' command, or using the examples under the
_b_i_n_d__s_c_r_i_p_t command above.
_D_e_b_u_g_g_i_n_g
There are three varieties of debugging in xxxxcccc. The script command (set
debug "on" or set debug "off") will control echoing of each line of a
script to the screen.
If the program was compiled with DEBUG set to 1 in xc.h, all screen
output will be captured in a file called _d_e_b_u_g._l_o_g in the current
directory, providing that it exists before entering xxxxcccc,,,, and providing
that output is not being diverted to a current capture file. The
_d_e_b_u_g._l_o_g file is overwritten each time xxxxcccc is run.
If you forgot to turn on capturing, if the program was compiled with
DEBUG set to 1, and if _d_e_b_u_g._l_o_g exists, all is not lost: your session
is recorded in _d_e_b_u_g._l_o_g.
Note that capturing to files is turned off when exiting terminal mode,
and this includes running the built-in B+ or XMODEM protocols.
Finally, in the xcb+.c module, there is a CIS_DEBUG definition line
which is normally commented out. If this definition is uncommented,
then a B+ transfer will record every byte in a file called _x_c._l_o_g.
This file is created if needed, in the current directory, and overwrit-
ten on each run of xxxxcccc.
Exit Codes
0000 Successful, uneventful completion.
1111 Error in command-line arguments.
2222 Failure in forking to execute a command or run a shell.
3333 No modem port specified on the command line, or contained in
the environment variable MODEM.
4444 Inability to create a LCK..file for the specified port.
5555 Inability to open the specified port.
6666 No environment variable TERM has been set.
7777 No entry for the current TERM setting in /etc/termcap.
8888 Problem caused by the 'ungetty' program.
Copyright
XXXXcccc and its source files and sample scripts and manual page are Copy-
right 1993 by Jean-Pierre Radley.
Permission is granted to the public to use this code in any manner,
without any warranty, implied or otherwise, of fitness for a particular
purpose.
By virtue of a restriction previously placed upon all code derivative
from xxxxccccoooommmmmmmm, the xxxxcccc code and associated files may not be sold by anyone
to anyone, nor incorporated into any product that is not also free.
It's OK to transfer them for free.
Authors
This manual page was written by Fred Buck (1989) and Jean-Pierre Radley
(1990, 1991, 1992, 1993). XXXXcccc itself is the product of many synergistic
wise minds. See the README document.
Version
This edition of the manual is for XC version 4.3 JPRadley 11 Sep 1993.